Custom Focus Types (OD PG)

Inside Macintosh: OpenDoc Programmer's Guide / Part 2 - Programming: Chapter 10 - Extending OpenDoc

Custom Focus Types
You can extend OpenDoc's model for shared-resource arbitration by creating your own focus module, allowing your parts to recognize and negotiate ownership of new kinds of focus.

Creating a Focus Module
The class ODFocusModule is an abstract superclass. OpenDoc uses instances of a subclass of ODFocusModule to assign ownership of specific types of focus to part editors. For normal program execution, you do not need to subclass ODFocusModule or even access the existing focus module objects directly. Your interaction with OpenDoc regarding focus ownership is mainly through the arbitrator.
You can, however, subclass ODFocusModule for new types of focus ownership, perhaps related to new types of peripheral devices or new classes of shared resources. For example, if you provide an exotic input device such as a 3D glove for a virtual reality game, you could create a focus module that tracked the ownership of input from the glove.
You define a new kind of focus to be handled by that focus module by creating an ISO string that is the name of the focus. As an example, the ISO string that defines the scrolling focus is "Scrolling." Currently defined foci are listed in Table 5-4.

Patching the arbitrator
It is possible to use custom focus modules to patch the functioning of the arbitrator in relation to all types of focus, although that practice is in general not recommended. In most cases there is no need for such drastic alteration of OpenDoc functionality.
If you subclass ODFocusModule, you need to implement a SOM constructor (somInit), a SOM destructor (somUninit), and an initialization method. Your initialization method should call (but not override) the InitFocusModule method of ODFocusModule.
Your focus module is responsible for maintaining the identities of the individual frames that own the foci managed by your focus module. You must implement the methods AcquireFocusOwner, SetFocusOwnership, UnsetFocusOwnership, and TransferFocusOwnership, all called by the arbitrator to request or change the owner of a focus.
You must also implement the methods BeginRelinquishFocus, CommitRelinquishFocus, and AbortRelinquishFocus, which your focus module uses in the two-stage process of relinquishing the ownership of a focus. The arbitrator calls these methods, and your focus module in turn calls the equivalent methods of the part that currently owns the focus.
You install a focus module by calling the RegisterFocus method of the arbitrator; you remove it by calling the UnregisterFocus method of the arbitrator.

The simple way
You can create a default focus module for any exclusive focus without having to subclass ODFocusModule. You simply pass the name of the focus and a value of kODNull (for the focus module object reference) to RegisterFocus. The arbitrator then creates and returns a focus module for your focus that has properties equivalent to those of the existing OpenDoc focus modules.

Focus Modules for Nonexclusive Foci
The arbitrator and focus modules allow foci to be nonexclusive, meaning that a given focus can have more than one owner. For instance, if video input is provided, a focus module for video focus might track the part or parts that are currently receiving video input.
If you create a focus module for nonexclusive foci, you must implement methods for testing exclusivity (IsFocusExclusive) and for allowing a caller to iterate over the owners of a focus (CreateOwnerIterator).